---
title: Using LlamaIndex Server
description: Running LlamaIndex workflows with both API endpoints and a user interface for interaction
---

# LlamaIndex Server

LlamaIndexServer is a Next.js-based application that allows you to quickly launch your [LlamaIndex Workflows](https://ts.llamaindex.ai/docs/llamaindex/modules/agents/workflows) and [Agent Workflows](https://ts.llamaindex.ai/docs/llamaindex/modules/agents/agent_workflow) as an API server with an optional chat UI. It provides a complete environment for running LlamaIndex workflows with both API endpoints and a user interface for interaction.

## Features

- Serving a workflow as a chatbot
- Built on Next.js for high performance and easy API development
- Optional built-in chat UI with extendable UI components
- Prebuilt development code

## Installation

```package-install
npm i @llamaindex/server
```

## Quick Start

Create index.ts file and add the following code:

```ts
import { LlamaIndexServer } from "@llamaindex/server";
import { wiki } from "@llamaindex/tools"; // or any other tool

const createWorkflow = () => agent({ tools: [wiki()] })

new LlamaIndexServer({
  workflow: createWorkflow,
  uiConfig: {
    appTitle: "LlamaIndex App",
    starterQuestions: ["Who is the first president of the United States?"],
  },
}).start();
```

## Running the Server

In the same directory as `index.ts`, run the following command to start the server:

  ```bash
  tsx index.ts
  ```
The server will start at `http://localhost:3000`

You can also make a request to the server:

  ```bash
  curl -X POST "http://localhost:3000/api/chat" -H "Content-Type: application/json" -d '{"message": "Who is the first president of the United States?"}'
  ```

## Configuration Options

The LlamaIndexServer accepts the following configuration

- `workflow`: A callable function that creates a workflow instance for each request
- `uiConfig`: An object to configure the chat UI containing the following properties:
  - `appTitle`: The title of the application (default: `"LlamaIndex App"`)
  - `starterQuestions`: List of starter questions for the chat UI (default: `[]`)
  - `componentsDir`: The directory for custom UI components rendering events emitted by the workflow. The default is undefined, which does not render custom UI components.
  - `llamaCloudIndexSelector`: Whether to show the LlamaCloud index selector in the chat UI (requires `LLAMA_CLOUD_API_KEY` to be set in the environment variables) (default: `false`)

LlamaIndexServer accepts all the configuration options from Nextjs Custom Server such as `port`, `hostname`, `dev`, etc.
See all Nextjs Custom Server options [here](https://nextjs.org/docs/app/building-your-application/configuring/custom-server).

## Default Endpoints and Features

### Chat Endpoint

The server includes a default chat endpoint at `/api/chat` for handling chat interactions.

### Chat UI

The server always provides a chat interface at the root path (`/`) with:

- Configurable starter questions
- Real-time chat interface
- API endpoint integration

### Static File Serving

- The server automatically mounts the `data` and `output` folders at `{server_url}{api_prefix}/files/data` (default: `/api/files/data`) and `{server_url}{api_prefix}/files/output` (default: `/api/files/output`) respectively.
- Your workflows can use both folders to store and access files. As a convention, the `data` folder is used for documents that are ingested and the `output` folder is used for documents that are generated by the workflow.


## Custom UI Components

The LlamaIndex server provides support for rendering workflow events using custom UI components, allowing you to extend and customize the chat interface.

### Overview

Custom UI components are a powerful feature that enables you to:

- Add custom interface elements to the chat UI using React JSX or TSX files
- Extend the default chat interface functionality
- Create specialized visualizations or interactions

### Configuration

Your workflow must emit events that fit this structure, allowing the LlamaIndex server to display the right UI components based on the event type.

```json
{
    "type": "<event_name>",
    "data": <data model>
}
```

### Server Setup

1. Initialize the LlamaIndex server with a component directory:

```ts
new LlamaIndexServer({
  workflow: createWorkflow,
  uiConfig: {
    appTitle: "LlamaIndex App",
    componentsDir: "components",
  },
}).start();
```

2. Add the custom component code to the directory following the naming pattern:

   - File Extension: `.jsx` and `.tsx` for React components
   - File Name: Should match the event type from your workflow (e.g., `deep_research_event.jsx` for handling `deep_research_event` type that you defined in your workflow). If there are TSX and JSX files with the same name, the TSX file will be used.
   - Component Name: Export a default React component named `Component` that receives props from the event data

   Example component structure:

   ```jsx
   function Component({ events }) {
       // Your component logic here
       return (
           // Your UI code here
       );
   }
   ```

## Best Practices

1. Always provide a workflow factory that creates fresh workflow instances
2. Use environment variables for sensitive configuration
3. Use starter questions to guide users in the chat UI

## Getting Started with a New Project

Want to start a new project with LlamaIndexServer? Check out our [create-llama](https://github.com/run-llama/create-llama) tool to quickly generate a new project with LlamaIndexServer.